Changes between Version 2 and Version 3 of TracStandalone


Ignore:
Timestamp:
Feb 5, 2015, 2:57:06 PM (5 years ago)
Author:
trac
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • TracStandalone

    v2 v3  
    1 = Tracd =
     1= Tracd
    22
    33Tracd is a lightweight standalone Trac web server.
    44It can be used in a variety of situations, from a test or development server to a multiprocess setup behind another web server used as a load balancer.
    55
    6 == Pros ==
     6== Pros
    77
    88 * Fewer dependencies: You don't need to install apache or any other web-server.
     
    1010 * Automatic reloading: For development, Tracd can be used in ''auto_reload'' mode, which will automatically restart the server whenever you make a change to the code (in Trac itself or in a plugin).
    1111
    12 == Cons ==
     12== Cons
    1313
    1414 * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd.
     
    1616   or [trac:wiki:STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy.
    1717
    18 == Usage examples ==
     18== Usage examples
    1919
    2020A single project on port 8080. (http://localhost:8080/)
    21 {{{
     21{{{#!sh
    2222 $ tracd -p 8080 /path/to/project
    2323}}}
    2424Strictly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use ''--hostname'' option.
    25 {{{
     25{{{#!sh
    2626 $ tracd --hostname=localhost -p 8080 /path/to/project
    2727}}}
    2828With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/)
    29 {{{
     29{{{#!sh
    3030 $ tracd -p 8080 /path/to/project1 /path/to/project2
    3131}}}
     
    3535
    3636An alternative way to serve multiple projects is to specify a parent directory in which each subdirectory is a Trac project, using the `-e` option. The example above could be rewritten:
    37 {{{
     37{{{#!sh
    3838 $ tracd -p 8080 -e /path/to
    3939}}}
    4040
    41 To exit the server on Windows, be sure to use {{{CTRL-BREAK}}} -- using {{{CTRL-C}}} will leave a Python process running in the background.
    42 
    43 == Installing as a Windows Service ==
    44 
    45 === Option 1 ===
     41To exit the server on Windows, be sure to use `CTRL-BREAK` -- using `CTRL-C` will leave a Python process running in the background.
     42
     43== Installing as a Windows Service
     44
     45=== Option 1
    4646To install as a Windows service, get the [http://www.google.com/search?q=srvany.exe SRVANY] utility and run:
    47 {{{
     47{{{#!cmd
    4848 C:\path\to\instsrv.exe tracd C:\path\to\srvany.exe
    4949 reg add HKLM\SYSTEM\CurrentControlSet\Services\tracd\Parameters /v Application /d "\"C:\path\to\python.exe\" \"C:\path\to\python\scripts\tracd-script.py\" <your tracd parameters>"
     
    5454
    5555If you want tracd to start automatically when you boot Windows, do:
    56 {{{
     56{{{#!cmd
    5757 sc config tracd start= auto
    5858}}}
     
    7474
    7575For Windows 7 User, srvany.exe may not be an option, so you can use [http://www.google.com/search?q=winserv.exe WINSERV] utility and run:
    76 {{{
     76{{{#!cmd
    7777"C:\path\to\winserv.exe" install tracd -displayname "tracd" -start auto "C:\path\to\python.exe" c:\path\to\python\scripts\tracd-script.py <your tracd parameters>"
    78 
    7978net start tracd
    8079}}}
    8180
    82 === Option 2 ===
     81=== Option 2
    8382
    8483Use [http://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [http://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service.
    8584
    86 === Option 3 ===
     85=== Option 3
    8786
    8887also cygwin's cygrunsrv.exe can be used:
    89 {{{
     88{{{#!sh
    9089$ cygrunsrv --install tracd --path /cygdrive/c/Python27/Scripts/tracd.exe --args '--port 8000 --env-parent-dir E:\IssueTrackers\Trac\Projects'
    9190$ net start tracd
    9291}}}
    9392
    94 == Using Authentication ==
     93== Using Authentication
    9594
    9695Tracd allows you to run Trac without the need for Apache, but you can take advantage of Apache's password tools (htpasswd and htdigest) to easily create a password file in the proper format for tracd to use in authentication. (It is also possible to create the password file without htpasswd or htdigest; see below for alternatives)
     
    101100
    102101The general format for using authentication is:
    103 {{{
     102{{{#!sh
    104103 $ tracd -p port --auth="base_project_dir,password_file_path,realm" project_path
    105104}}}
     
    117116Examples:
    118117
    119 {{{
     118{{{#!sh
    120119 $ tracd -p 8080 \
    121120   --auth="project1,/path/to/passwordfile,mycompany.com" /path/to/project1
     
    123122
    124123Of course, the password file can be be shared so that it is used for more than one project:
    125 {{{
     124{{{#!sh
    126125 $ tracd -p 8080 \
    127126   --auth="project1,/path/to/passwordfile,mycompany.com" \
     
    131130
    132131Another way to share the password file is to specify "*" for the project name:
    133 {{{
     132{{{#!sh
    134133 $ tracd -p 8080 \
    135134   --auth="*,/path/to/users.htdigest,mycompany.com" \
     
    137136}}}
    138137
    139 === Basic Authorization: Using a htpasswd password file ===
     138=== Basic Authorization: Using a htpasswd password file
    140139This section describes how to use `tracd` with Apache .htpasswd files.
    141140
     
    145144
    146145To create a .htpasswd file use Apache's `htpasswd` command (see [#GeneratingPasswordsWithoutApache below] for a method to create these files without using Apache):
    147 {{{
     146{{{#!sh
    148147 $ sudo htpasswd -c /path/to/env/.htpasswd username
    149148}}}
    150149then for additional users:
    151 {{{
     150{{{#!sh
    152151 $ sudo htpasswd /path/to/env/.htpasswd username2
    153152}}}
    154153
    155154Then to start `tracd` run something like this:
    156 {{{
     155{{{#!sh
    157156 $ tracd -p 8080 --basic-auth="projectdirname,/fullpath/environmentname/.htpasswd,realmname" /fullpath/environmentname
    158157}}}
    159158
    160159For example:
    161 {{{
     160{{{#!sh
    162161 $ tracd -p 8080 --basic-auth="testenv,/srv/tracenv/testenv/.htpasswd,My Test Env" /srv/tracenv/testenv
    163162}}}
    164163''Note:'' You might need to pass "-m" as a parameter to htpasswd on some platforms (OpenBSD).
    165164
    166 === Digest authentication: Using a htdigest password file ===
     165=== Digest authentication: Using a htdigest password file
    167166
    168167If you have Apache available, you can use the htdigest command to generate the password file. Type 'htdigest' to get some usage instructions, or read [http://httpd.apache.org/docs/2.0/programs/htdigest.html this page] from the Apache manual to get precise instructions.  You'll be prompted for a password to enter for each user that you create.  For the name of the password file, you can use whatever you like, but if you use something like `users.htdigest` it will remind you what the file contains. As a suggestion, put it in your <projectname>/conf folder along with the [TracIni trac.ini] file.
     
    170169Note that you can start tracd without the `--auth` argument, but if you click on the ''Login'' link you will get an error.
    171170
    172 === Generating Passwords Without Apache ===
     171=== Generating Passwords Without Apache
    173172
    174173Basic Authorization can be accomplished via this [http://aspirine.org/htpasswd_en.html online HTTP Password generator] which also supports `SHA-1`.  Copy the generated password-hash line to the .htpasswd file on your system. Note that Windows Python lacks the "crypt" module that is the default hash type for htpasswd ; Windows Python can grok MD5 password hashes just fine and you should use MD5.
     
    176175You can use this simple Python script to generate a '''digest''' password file:
    177176
    178 {{{
    179 #!python
     177{{{#!python
    180178from optparse import OptionParser
    181179# The md5 module is deprecated in Python 2.5
     
    210208Note: If you use the above script you must set the realm in the `--auth` argument to '''`trac`'''. Example usage (assuming you saved the script as trac-digest.py):
    211209
    212 {{{
     210{{{#!sh
    213211 $ python trac-digest.py -u username -p password >> c:\digest.txt
    214212 $ tracd --port 8000 --auth=proj_name,c:\digest.txt,trac c:\path\to\proj_name
     
    225223}}}
    226224
    227 == Reference ==
     225== Reference
    228226
    229227Here's the online help, as a reminder (`tracd --help`):
     
    261259Use the -d option so that tracd doesn't hang if you close the terminal window where tracd was started.
    262260
    263 == Tips ==
    264 
    265 === Serving static content ===
     261== Tips
     262
     263=== Serving static content
    266264
    267265If `tracd` is the only web server used for the project,
     
    274272Example: given a `$TRAC_ENV/htdocs/software-0.1.tar.gz` file,
    275273the corresponding relative URL would be `/<project_name>/chrome/site/software-0.1.tar.gz`,
    276 which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax).
    277 
    278  ''Support for `htdocs:` TracLinks syntax was added in version 0.10''
     274which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax).
    279275
    280276=== Using tracd behind a proxy
     
    289285
    290286=== Authentication for tracd behind a proxy
    291 It is convenient to provide central external authentication to your tracd instances, instead of using {{{--basic-auth}}}. There is some discussion about this in #9206.
     287It is convenient to provide central external authentication to your tracd instances, instead of using `--basic-auth`. There is some discussion about this in #9206.
    292288
    293289Below is example configuration based on Apache 2.2, mod_proxy, mod_authnz_ldap.
     
    295291First we bring tracd into Apache's location namespace.
    296292
    297 {{{
     293{{{#!apache
    298294<Location /project/proxified>
    299295        Require ldap-group cn=somegroup, ou=Groups,dc=domain.com
     
    306302
    307303Then we need a single file plugin to recognize HTTP_REMOTE_USER header as valid authentication source. HTTP headers like '''HTTP_FOO_BAR''' will get converted to '''Foo-Bar''' during processing. Name it something like '''remote-user-auth.py''' and drop it into '''proxified/plugins''' directory:
    308 {{{
    309 #!python
     304{{{#!python
    310305from trac.core import *
    311306from trac.config import BoolOption
     
    328323
    329324Add this new parameter to your TracIni:
    330 {{{
    331 ...
     325{{{#!ini
    332326[trac]
    333327...
     
    337331
    338332Run tracd:
    339 {{{
     333{{{#!sh
    340334tracd -p 8101 -r -s proxified --base-path=/project/proxified
    341335}}}
     
    344338
    345339Global config (e.g. `/srv/trac/conf/trac.ini`):
    346 {{{
     340{{{#!ini
    347341[components]
    348342remote-user-auth.* = enabled
     
    354348
    355349Environment config (e.g. `/srv/trac/envs/myenv`):
    356 {{{
     350{{{#!ini
    357351[inherit]
    358352file = /srv/trac/conf/trac.ini
    359353}}}
    360354
    361 === Serving a different base path than / ===
     355=== Serving a different base path than /
    362356Tracd supports serving projects with different base urls than /<project>. The parameter name to change this is
    363 {{{
     357{{{#!sh
    364358 $ tracd --base-path=/some/path
    365359}}}