Changes between Version 2 and Version 3 of TracFastCgi

Timestamp:

2014-01-26 00:59:50 (11 years ago)

Author:

trac

Comment:

--

TracFastCgi

@@ +1 @@
+[[PageOutline]]
+
 = Trac with FastCGI =
 
-[http://www.fastcgi.com/ FastCGI] interface allows Trac to remain resident much like with [wiki:TracModPython mod_python]. It is faster than external CGI interfaces which must start a new process for each request. However, unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], i.e. run with different permissions than web server. Additionally, it is supported by much wider variety of web servers.
-
-'''Note for Windows:''' Trac's FastCGI does not run under Windows, as Windows does not implement `Socket.fromfd`, which is used by `_fcgi.py`. If you want to connect to IIS, you may want to try [trac:TracOnWindowsIisAjp AJP].
+[http://www.fastcgi.com/ FastCGI] interface allows Trac to remain resident much like with [wiki:TracModPython mod_python] or [wiki:TracModWSGI mod_wsgi]. It is faster than external CGI interfaces which must start a new process for each request.  Additionally, it is supported by much wider variety of web servers.
+
+Note that unlike mod_python, FastCGI supports [http://httpd.apache.org/docs/suexec.html Apache SuEXEC], i.e. run with different permissions than web server running with (`mod_wsgi` supports the `WSGIDaemonProcess` with user / group parameters to achieve the same effect).
+
+'''Note for Windows:''' Trac's FastCGI does not run under Windows, as Windows does not implement `Socket.fromfd`, which is used by `_fcgi.py`. If you want to connect to IIS, you may want to try [trac:TracOnWindowsIisAjp AJP]/[trac:TracOnWindowsIisAjp ISAPI].
+
+[[PageOutline(2-3,Overview,inline)]]
+
 
 == Simple Apache configuration ==
@@ -10 +17 @@
 `mod_fcgid` (preferred). The latter is more up-to-date.
 
-==== setup with `mod_fastcgi` ====
+The following sections focus on the FCGI specific setup, see also [wiki:TracModWSGI#ConfiguringAuthentication] for configuring the authentication in Apache.
+
+Regardless of which cgi module is used, be sure the web server has executable permissions on the cgi-bin folder. While FastCGI will throw specific permissions errors, mod_fcgid will throw an ambiguous error if this has not been done. (Connection reset by peer: mod_fcgid: error reading data from FastCGI server) 
+
+=== Set up with `mod_fastcgi` ===
 `mod_fastcgi` uses `FastCgiIpcDir` and `FastCgiConfig` directives that should be added to an appropriate Apache configuration file:
 {{{
@@ -27 +38 @@
 calling `trac.fcgi` instead of `trac.cgi`.
 
-You can set up the `TRAC_ENV` as an overall default:
+Add the following to the Apache configuration file (below the `FastCgiIpcDir` line) if you intend to set up the `TRAC_ENV` as an overall default:
 {{{
 FastCgiConfig -initial-env TRAC_ENV=/path/to/env/trac
 }}}
 
-Or you can serve multiple Trac projects in a directory like:
+Alternatively, you can serve multiple Trac projects in a directory by adding this:
 {{{
 FastCgiConfig -initial-env TRAC_ENV_PARENT_DIR=/parent/dir/of/projects
 }}}
 
-==== setup with `mod_fcgid` ====
+=== Set up with `mod_fcgid` ===
 Configure `ScriptAlias` (see TracCgi for details), but call `trac.fcgi`
 instead of `trac.cgi`. Note that slash at the end - it is important.
@@ -44 +55 @@
 }}}
 
-To setup Trac environment for `mod_fcgid` it is necessary to use
+To set up Trac environment for `mod_fcgid` it is necessary to use
 `DefaultInitEnv` directive. It cannot be used in `Directory` or
 `Location` context, so if you need to support multiple projects, try
@@ -53 +64 @@
 }}}
 
-==== alternative environment setup ====
-A better method to specify path to Trac environment it to embed the path
+=== alternative environment setup ===
+A better method to specify path to Trac environment is to embed the path
 into `trac.fcgi` script itself. That doesn't require configuration of server
 environment variables, works for both FastCgi modules
@@ -93 +104 @@
 
 After doing this, we will just have to create a new rule managed by the SCGI handler to access Trac. It can be created in a new virtual server, trac.example.net for instance, and will only need two rules. The '''default''' one will use the SCGI handler associated to the previously created information source.
-The second rule will be there to serve the few static files needed to correctly display the Trac interface. Create it as ''Directory rule'' for ''/chrome/common'' and just set it to the ''Static files'' handler and with a ''Document root'' that points to the appropriate files: ''/usr/share/trac/htdocs/''
+The second rule will be there to serve the few static files needed to correctly display the Trac interface. Create it as ''Directory rule'' for ''/common'' and just set it to the ''Static files'' handler and with a ''Document root'' that points to the appropriate files: ''$TRAC_LOCAL/htdocs/'' (where $TRAC_LOCAL is a directory defined by the user or the system administrator to place local trac resources).
 
 Note:\\
@@ -101 +112 @@
 sudo apt-get install python-flup
 }}}
+
 
 == Simple Lighttpd Configuration ==
@@ -130 +142 @@
 using `bin-environment` (as in the section above on Apache configuration).
 
-Note that lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example, see #Trac2418. This should be fixed since lighttpd 1.4.23, and you may need to add `"fix-root-scriptname" => "enable"` as parameter of fastcgi.server.
+Note that lighttpd has a bug related to 'SCRIPT_NAME' and 'PATH_INFO' when the uri of fastcgi.server is '/' instead of '/trac' in this example (see [trac:#2418]). This should be fixed since lighttpd 1.4.23, and you may need to add `"fix-root-scriptname" => "enable"` as parameter of fastcgi.server.
 
 For using two projects with lighttpd add the following to your `lighttpd.conf`:
@@ -159 +171 @@
 Note that the above will result in different processes in any event, even
 if both are running from the same `trac.fcgi` script.
+
 {{{
 #!div class=important
 '''Note''' It's very important the order on which server.modules are loaded, if mod_auth is not loaded '''BEFORE''' mod_fastcgi, then the server will fail to authenticate the user.
 }}}
+
 For authentication you should enable mod_auth in lighttpd.conf 'server.modules', select auth.backend and auth rules:
 {{{
@@ -210 +224 @@
 server.modules += ("mod_alias")
 
-# Setup an alias for the static resources
+# Set up an alias for the static resources
 alias.url = ("/trac/chrome/common" => "/usr/share/trac/htdocs")
 
@@ -276 +290 @@
 For details about languages specification see [trac:TracFaq TracFaq] question 2.13.
 
-Other important information like [http://trac.lighttpd.net/trac/wiki/TracInstall this updated TracInstall page], [wiki:TracCgi#MappingStaticResources and this] are useful for non-fastcgi specific installation aspects.
-
-If you use trac-0.9, read [http://lists.edgewall.com/archive/trac/2005-November/005311.html about small bug]
+Other important information like the [wiki:TracInstall#MappingStaticResources mapping static resources advices] are useful for non-fastcgi specific installation aspects.
+]
 
 Relaunch lighttpd, and browse to `http://yourhost.example.org/trac` to access Trac.
@@ -284 +297 @@
 Note about running lighttpd with reduced permissions:
 
-  If nothing else helps and trac.fcgi doesn't start with lighttpd settings `server.username = "www-data"`, `server.groupname = "www-data"`, then in the `bin-environment` section set `PYTHON_EGG_CACHE` to the home directory of `www-data` or some other directory accessible to this account for writing.
+If nothing else helps and trac.fcgi doesn't start with lighttpd settings `server.username = "www-data"`, `server.groupname = "www-data"`, then in the `bin-environment` section set `PYTHON_EGG_CACHE` to the home directory of `www-data` or some other directory accessible to this account for writing.
 
 
@@ -292 +305 @@
 
 !LiteSpeed web server is an event-driven asynchronous Apache replacement designed from the ground-up to be secure, scalable, and operate with minimal resources. !LiteSpeed can operate directly from an Apache config file and is targeted for business-critical environments.
-
-=== Setup ===
 
  1. Please make sure you have first have a working install of a Trac project. Test install with “tracd” first.
@@ -354 +365 @@
 }}}
 
+
 == Simple Nginx Configuration ==
 
- 1. Nginx configuration snippet - confirmed to work on 0.6.32
+Nginx is able to communicate with FastCGI processes, but can not spawn them. So you need to start FastCGI server for Trac separately.
+
+ 1. Nginx configuration with basic authentication handled by Nginx - confirmed to work on 0.6.32
 {{{
     server {
@@ -375 +389 @@
         if ($uri ~ ^/(.*)) {
              set $path_info /$1;
+        }
+
+        # it makes sense to serve static resources through Nginx
+        location /chrome/ {
+             alias /home/trac/instance/static/htdocs/;
         }
 
@@ -403 +422 @@
             fastcgi_param  SERVER_PORT        $server_port;
             fastcgi_param  SERVER_PROTOCOL    $server_protocol;
-            fastcgi_param  QUERY_STRING     $query_string;
-
-            # for authentication to work
+            fastcgi_param  QUERY_STRING       $query_string;
+
+            # For Nginx authentication to work - do not forget to comment these
+            # lines if not using Nginx for authentication
             fastcgi_param  AUTH_USER          $remote_user;
             fastcgi_param  REMOTE_USER        $remote_user;
+
+            # for ip to work
+            fastcgi_param REMOTE_ADDR         $remote_addr;
+
+            # For attchments to work
+            fastcgi_param    CONTENT_TYPE     $content_type;
+            fastcgi_param    CONTENT_LENGTH   $content_length;
         }
     }