| 3 | | Since version 0.9, Trac supports being run through the [http://www.fastcgi.com/ FastCGI] interface. Like [wiki:TracModPython mod_python], this allows Trac to remain resident, and is faster than external CGI interfaces which must start a new process for each request. However, unlike mod_python, it is able to support [http://httpd.apache.org/docs/suexec.html SuEXEC]. Additionally, it is supported by much wider variety of web servers. |
| | 3 | [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. |
| | 4 | |
| | 5 | '''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]. |
| 39 | | But neither of these will work for `mod_fcgid`. A similar but partial |
| 40 | | solution for `mod_fcgid` is: |
| 41 | | {{{ |
| 42 | | DefaultInitEnv TRAC_ENV /path/to/env/trac/ |
| 43 | | }}} |
| 44 | | But this cannot be used in `Directory` or `Location` context, which makes it |
| 45 | | difficult to support multiple projects. |
| 46 | | |
| 47 | | A better method which works for both of these modules (and for [http://www.lighttpd.net/ lighttpd] and CGI as well), because it involves |
| 48 | | no server configuration settings for environment variables, is to set one |
| 49 | | of the variables in `trac.fcgi`, e.g.: |
| | 39 | ==== setup with `mod_fcgid` ==== |
| | 40 | Configure `ScriptAlias` (see TracCgi for details), but call `trac.fcgi` |
| | 41 | instead of `trac.cgi`. Note that slash at the end - it is important. |
| | 42 | {{{ |
| | 43 | ScriptAlias /trac /path/to/www/trac/cgi-bin/trac.fcgi/ |
| | 44 | }}} |
| | 45 | |
| | 46 | To setup Trac environment for `mod_fcgid` it is necessary to use |
| | 47 | `FCGIDDefaultInitEnv` directive. It cannot be used in `Directory` or |
| | 48 | `Location` context, so if you need to support multiple projects, try |
| | 49 | alternative environment setup below. |
| | 50 | |
| | 51 | {{{ |
| | 52 | FCGIDDefaultInitEnv TRAC_ENV /path/to/env/trac/ |
| | 53 | }}} |
| | 54 | |
| | 55 | ==== alternative environment setup ==== |
| | 56 | A better method to specify path to Trac environment it to embed the path |
| | 57 | into `trac.fcgi` script itself. That doesn't require configuration of server |
| | 58 | environment variables, works for both FastCgi modules |
| | 59 | (and for [http://www.lighttpd.net/ lighttpd] and CGI as well): |
| 60 | | Using this method, different projects can be supported by using different |
| 61 | | `.fcgi` scripts with different `ScriptAliases`, copying and appropriately |
| 62 | | renaming `trac.fcgi` and adding the above code to create each such script. |
| | 70 | With this method different projects can be supported by using different |
| | 71 | `.fcgi` scripts with different `ScriptAliases`. |
| | 72 | |
| | 73 | See [https://coderanger.net/~coderanger/httpd/fcgi_example.conf this fcgid example config] which uses a !ScriptAlias directive with trac.fcgi with a trailing / like this: |
| | 74 | {{{ |
| | 75 | ScriptAlias / /srv/tracsite/cgi-bin/trac.fcgi/ |
| | 76 | }}} |
| | 77 | |
| | 78 | == Simple Cherokee Configuration == |
| | 79 | |
| | 80 | The configuration on Cherokee's side is quite simple. You will only need to know that you can spawn Trac as an SCGI process. |
| | 81 | You can either start it manually, or better yet, automatically by letting Cherokee spawn the server whenever it is down. |
| | 82 | First set up an information source in cherokee-admin with a local interpreter. |
| | 83 | |
| | 84 | {{{ |
| | 85 | Host: |
| | 86 | localhost:4433 |
| | 87 | |
| | 88 | Interpreter: |
| | 89 | /usr/bin/tracd —single-env —daemonize —protocol=scgi —hostname=localhost —port=4433 /path/to/project/ |
| | 90 | }}} |
| | 91 | |
| | 92 | If the port was not reachable, the interpreter command would be launched. Note that, in the definition of the information source, you will have to manually launch the spawner if you use a ''Remote host'' as ''Information source'' instead of a ''Local interpreter''. |
| | 93 | |
| | 94 | 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. |
| | 95 | 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/'' |
| | 347 | === Simple Nginx Configuration === |
| | 348 | |
| | 349 | 1) Nginx configuration snippet - confirmed to work on 0.6.32 |
| | 350 | {{{ |
| | 351 | server { |
| | 352 | listen 10.9.8.7:443; |
| | 353 | server_name trac.example; |
| | 354 | |
| | 355 | ssl on; |
| | 356 | ssl_certificate /etc/ssl/trac.example.crt; |
| | 357 | ssl_certificate_key /etc/ssl/trac.example.key; |
| | 358 | |
| | 359 | ssl_session_timeout 5m; |
| | 360 | |
| | 361 | ssl_protocols SSLv2 SSLv3 TLSv1; |
| | 362 | ssl_ciphers ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; |
| | 363 | ssl_prefer_server_ciphers on; |
| | 364 | |
| | 365 | # (Or ``^/some/prefix/(.*)``. |
| | 366 | if ($uri ~ ^/(.*)) { |
| | 367 | set $path_info /$1; |
| | 368 | } |
| | 369 | |
| | 370 | # You can copy this whole location to ``location [/some/prefix]/login`` |
| | 371 | # and remove the auth entries below if you want Trac to enforce |
| | 372 | # authorization where appropriate instead of needing to authenticate |
| | 373 | # for accessing the whole site. |
| | 374 | # (Or ``location /some/prefix``.) |
| | 375 | location / { |
| | 376 | auth_basic "trac realm"; |
| | 377 | auth_basic_user_file /home/trac/htpasswd; |
| | 378 | |
| | 379 | # socket address |
| | 380 | fastcgi_pass unix:/home/trac/run/instance.sock; |
| | 381 | |
| | 382 | # python - wsgi specific |
| | 383 | fastcgi_param HTTPS on; |
| | 384 | |
| | 385 | ## WSGI REQUIRED VARIABLES |
| | 386 | # WSGI application name - trac instance prefix. |
| | 387 | # (Or ``fastcgi_param SCRIPT_NAME /some/prefix``.) |
| | 388 | fastcgi_param SCRIPT_NAME ""; |
| | 389 | fastcgi_param PATH_INFO $path_info; |
| | 390 | |
| | 391 | ## WSGI NEEDED VARIABLES - trac warns about them |
| | 392 | fastcgi_param REQUEST_METHOD $request_method; |
| | 393 | fastcgi_param SERVER_NAME $server_name; |
| | 394 | fastcgi_param SERVER_PORT $server_port; |
| | 395 | fastcgi_param SERVER_PROTOCOL $server_protocol; |
| | 396 | |
| | 397 | # for authentication to work |
| | 398 | fastcgi_param AUTH_USER $remote_user; |
| | 399 | fastcgi_param REMOTE_USER $remote_user; |
| | 400 | } |
| | 401 | } |
| | 402 | }}} |
| | 403 | |
| | 404 | 2) Modified trac.fcgi: |
| | 405 | |
| | 406 | {{{ |
| | 407 | #!/usr/bin/env python |
| | 408 | import os |
| | 409 | sockaddr = '/home/trac/run/instance.sock' |
| | 410 | os.environ['TRAC_ENV'] = '/home/trac/instance' |
| | 411 | |
| | 412 | try: |
| | 413 | from trac.web.main import dispatch_request |
| | 414 | import trac.web._fcgi |
| | 415 | |
| | 416 | fcgiserv = trac.web._fcgi.WSGIServer(dispatch_request, |
| | 417 | bindAddress = sockaddr, umask = 7) |
| | 418 | fcgiserv.run() |
| | 419 | |
| | 420 | except SystemExit: |
| | 421 | raise |
| | 422 | except Exception, e: |
| | 423 | print 'Content-Type: text/plain\r\n\r\n', |
| | 424 | print 'Oops...' |
| | 425 | print |
| | 426 | print 'Trac detected an internal error:' |
| | 427 | print |
| | 428 | print e |
| | 429 | print |
| | 430 | import traceback |
| | 431 | import StringIO |
| | 432 | tb = StringIO.StringIO() |
| | 433 | traceback.print_exc(file=tb) |
| | 434 | print tb.getvalue() |
| | 435 | |
| | 436 | }}} |
| | 437 | |
| | 438 | 3) reload nginx and launch trac.fcgi like that: |
| | 439 | |
| | 440 | {{{ |
| | 441 | trac@trac.example ~ $ ./trac-standalone-fcgi.py |
| | 442 | }}} |
| | 443 | |
| | 444 | The above assumes that: |
| | 445 | * There is a user named 'trac' for running trac instances and keeping trac environments in its home directory. |
| | 446 | * /home/trac/instance contains a trac environment |
| | 447 | * /home/trac/htpasswd contains authentication information |
| | 448 | * /home/trac/run is owned by the same group the nginx runs under |
| | 449 | * and if your system is Linux the /home/trac/run has setgid bit set (chmod g+s run) |
| | 450 | * and patch from ticket #T7239 is applied, or you'll have to fix the socket file permissions every time |
| | 451 | |
| | 452 | Unfortunately nginx does not support variable expansion in fastcgi_pass directive. |
| | 453 | Thus it is not possible to serve multiple trac instances from one server block. |
| | 454 | |
| | 455 | If you worry enough about security, run trac instances under separate users. |
| | 456 | |
| | 457 | Another way to run trac as a FCGI external application is offered in ticket #T6224 |
| | 458 | |
